Specifying Information For Exporting

When the Assistant creates a new project, it supplies default values for the attributes that must be specified. Most of these values are set to UNSPECIFIED to indicate that you must modify this attribute. Some attributes do not have a default value because there is no reasonable one; also, supplying a default value could cause the wrappers to be built with incorrect values.

The one value that is set by default in most cases is the Convert Majority flag, used if the value is an array. The default setting for this attribute (True) provides the most expected behavior. For more information, see Converting Array Majority.

Note that in the IDL language, parameters are optional, so the Assistant does not require the user to export every parameter that is retrieved from the IDL source object and presented in the Assistant. It is up to the user to decide which parameters should be exported. This might require defensive programming in the IDL source object to ensure that parameters are not used if they are not supplied.

Information that can be specified includes:

Bridge Information: Defines general wrapper object information, the output directory, package name (Java only) and GUIDS settings (COM only)
Source Object Information: Indicates whether the object is drawable or not (this cannot be changed)
Property Information: Defines the property data type, whether it is an array (and the array majority if it is), and whether or not it is to be exported
Method Information: Defines the export characteristics of a procedure or function method, and defines the return value data type and array characteristics if the method is a function
Parameter Information: Defines the mutability, data type, array characteristics and export selection for method parameters

See Parameter Passing and Type Conversion for important information about passing objects, arrays and variables as parameters.

About the Export Property

The first (and only the first time) any attribute of a property, method, or parameter other than Export is set, the item has its Export property set to True. This behavior is provided as a convenience.

Converting Array Majority

The Convert Majority property may be an option for a property, function return value or method parameter that is defined as an array (the Array property is True). The rules for the Convert Majority property vary depending on destination (COM or Java) and whether the array is a property value, function return value or method parameter. The settings and default values are described below.

Where to Specify	Can Specify in COM?	Can Specify in Java?
Get Property	No (arrays always converted)	Yes (default is to convert)
Set Property	Yes (default is to convert)	Yes (default is to convert)
Function return values	No (arrays always converted)	Yes (default is to convert)
Procedure parameters	Yes (default is to convert)	Yes (default is to convert)

See the following for more information on these rules:

Property Information
Method Information
Parameter Information

Note: For COM wrappers, you could theoretically set the Convert Majority flag for the property setting call but not the property retrieval call. In practice, the Assistant uses one flag to control the Convert Majority setting for both Get and Set Property, and so for COM, the setting for properties is always Convert Majority, which is set to True and disabled.

For more information on array majority, see Multidimensional Array Storage and Access. Also see Array Order Conversion.

Supported Data Types

The following data types are supported with the Export Bridge technology.

COM	Unsigned char Char Short Unsigned short Long Unsigned long LONGLONG	ULONGLONG Float Double BSTR IUnknown* VARIANT
Java	JIDLNumber JIDLObjectI JIDLString

Note: See IDL Java Object API for information on JIDL* objects.

Bridge Information

The project has general information about the bridge being used (COM or Java).

The following describes the general bridge information’s properties and values

Property	Value
Name	Defaults to “IDL Export Bridge Project for <dest>” where <dest> is “COM” or “Java.” Displayed in the sheet header only, it is distinct from the project filename and source object classname and cannot be modified.
Source object classname	Specified by selection of IDL object definition file. The file must be selected, rather than specification of the object by name only. Because this value is obtained from the source object filename, the capitalization is the same as the filename.
Output classname	Defaults to IDL source object class name; must be non-null and a valid IDL identifier. Because this value is obtained from the source object filename, the capitalization is the same as the filename.
Process name	Defaults to ‘Default_Process_Name’; must be non-null and valid IDL identifier
Output directory	Defaults to location of source object file (.pro or .sav); independent from location of project file and source file (except for initial default to source location).

The other properties displayed for the project depends on which bridge it is using: COM or Java. The following describes COM-specific values.

Property	Value
Regenerate GUIDs	On the first build operation, GUIDS are always generated, so this property is desensitized until after the first build. On subsequent builds, if Regenerate GUIDs is False, the existing GUIDs are used, allowing a developer to use the newly built object without re-registering. If Regenerate GUIDs is true, new GUIDS will be created during a build operation. Any time GUIDs are regenerated during a build operation. they are saved and can be used by setting Regenerate GUIDs to False.
Explicit CreateObject	Note: This property is obsolete. By default, graphical COM objects (ActiveX objects) call the createObject method automatically when the control is created. If this property is set to True, the automatic call to the createObject method is removed; the client code must then explicitly call one of the CreateObject or CreateObjectEx methods to create the IDL process. This property is disabled for nongraphical COM objects, which always require an explict call to one of the CreateObject methods.

Property

Value

Regenerate GUIDs

On the first build operation, GUIDS are always generated, so this property is desensitized until after the first build. On subsequent builds, if Regenerate GUIDs is False, the existing GUIDs are used, allowing a developer to use the newly built object without re-registering. If Regenerate GUIDs is true, new GUIDS will be created during a build operation. Any time GUIDs are regenerated during a build operation. they are saved and can be used by setting Regenerate GUIDs to False.

Explicit CreateObject

Note: This property is obsolete.

By default, graphical COM objects (ActiveX objects) call the createObject method automatically when the control is created. If this property is set to True, the automatic call to the createObject method is removed; the client code must then explicitly call one of the CreateObject or CreateObjectEx methods to create the IDL process. This property is disabled for nongraphical COM objects, which always require an explict call to one of the CreateObject methods.

The following describes Java-specific properties and values.

Property	Value
Package name	Defaults to source object class name. Because this value is obtained from the source object filename, the capitalization is the same as the filename. This property is optional and can be blank. If blank, the Java file and class file will be created in the output directory. If not blank, the name is used to create one or more subdirectories below the output directory. Period characters are separator characters that produce a directory hierarchy in the resulting subdirectory for the result. Each segment between period characters must be a valid identifier.

Property

Value

Package name

Defaults to source object class name. Because this value is obtained from the source object filename, the capitalization is the same as the filename.

This property is optional and can be blank. If blank, the Java file and class file will be created in the output directory. If not blank, the name is used to create one or more subdirectories below the output directory. Period characters are separator characters that produce a directory hierarchy in the resulting subdirectory for the result. Each segment between period characters must be a valid identifier.

Source Object Information

The source object for which you are making a wrapper has its own set of properties.

The following describes the characteristics of the source object.

Property	Value
Name	Name of this IDL source object; specified when project was created and shown in the sheet header only
Drawable object	True if IDL source object is a subclass of IDLitWindow, IDLgrWindow, or IDLitDirectWindow; otherwise False.

Property Information

Each property of the source object has its own set of properties.

The following describes the properties and values of the source object’s properties.

Property	Value
Name	Name of the object’s property; shown in the sheet header only.
Type	One of the types supported by the Export Bridge technology. For the list, see Supported Data Types.
Array	Indicates if property is of type array: True if it is, False otherwise. If True, Convert Majority is sensitive.
Convert Majority	Sensitive only if Array is True. Set to True if the property value is an array and needs to be converted when setting the property. (For COM, when retrieving a property value, the majority is always converted regardless of this attribute setting.) The default value for both COM and Java is True. For more information, see Converting Array Majority.
Export	Indicates if the Assistant will export this property: True if it will, False otherwise.

About Property Extraction

The object properties are extracted from the IDL source object by compiling the list of all keywords on either or both of the SetProperty and GetProperty methods of the object.

The following factors are not used to determine source object properties:

Whether a property is registered or not (the export bridges do not require that an object uses the component framework)
The presence of a member variable in the source object's definition structure
Keywords to the object's Init method

Note: Properties of built-in superclasses are not extracted (see Exporting a Source Object’s Superclasses). To obtain wrapper routines to get or set a superclass property, you must add an explicit property handler to your SetProperty and/or GetProperty methods for the superclass property.

Method Information

Each method of the source object has its own set of properties. The following figure displays a procedure’s property information.

The following table describes the procedure information’s properties and values.

Property	Value
Name	Name of the procedure; shown in the sheet header only.
Output Method Name	The name of the wrapper method in the wrapper object. Defaults to the method name obtained from the source object, but can be changed to reflect native platform naming conventions and case. Regardless of the output method name, the wrapper method will call through the Export Bridge technology layers to the original source object method name in the IDL object.
Export	Indicates if the Assistant will export this property: True if it will, False otherwise.

The following figure shows the property information for a function.

The following describes the function information’s properties and values. In addition to the values that can be specified for procedure methods above), the following can also be defined.

Property	Value
Return Type	One of the types supported by the Export Bridge technology. For the list, see Supported Data Types.
Array	Indicates if property is of type array: True if it is, False otherwise. If True and the destination is Java, Convert Majority is sensitive.
Convert Majority	Sensitive only if Array is True and the destination is Java. Set to True if the property value is an array and needs to be converted when setting the property. (For COM, when retrieving a property value, the majority is always converted regardless of this setting, which is why this property does not appear with COM.) The default value is True. For more information, see Converting Array Majority.

Parameter Information

Each parameter of the source object’s methods has its own set of properties.

Note: If a method parameter has its Export property set to True, all parameters of the method to the left of the current parameter are marked for export as well so as to not leave holes in the parameters list and cause parameters to be out of sequence.
If a parameter has its Export property set to False, all parameters to the right will also have their Export property set to False. If a parameter has its Export property set to True, the parent method will have its Export property set to True.

The following describes the parameter information’s properties and values.

Property	Value
Name	Name of the procedure; shown in the sheet header only.
Mutability	Either In or In/Out. Use In for parameters that are constant (In- Only, meaning that their values cannot be changed). Use In/Out for parameters that are not constant and require a value to be passed back to the caller (can be In/Out or Out-only).
Return Type	One of the types supported by the Export Bridge technology. For the list, see Supported Data Types.
Array	Indicates if property is of type array: True if it is, False otherwise. If True, Convert Majority is sensitive.
Convert Majority	Sensitive only if Array is True. Set to True if the property value is an array and needs to be converted when setting the property. The default value is True. For more information, see Converting Array Majority.
Export	Indicates if the Assistant will export this property: True if it will, False otherwise.